home *** CD-ROM | disk | FTP | other *** search
/ Almathera Ten Pack 3: CDPD 3 / Almathera Ten on Ten - Disc 3: CDPD3.iso / fish / 726-750 / 743 / turbodex / dex.bak < prev    next >
Text File  |  1995-03-18  |  57KB  |  1,434 lines
  1.  
  2.                     TurboDEX Compiler v1.15 by $#%!
  3.  
  4.                              M A N U A L
  5.  
  6.  
  7.         Contents:
  8.  
  9.         1. Introduction, The Features
  10.         2. Installation And Running
  11.         3. The Language In General
  12.                 4. Step by step Tutorials
  13.         5. Alfabetical Overview Of Instructions
  14.                 6. Function() overview.
  15.                 7. Advanced Programming And Language Info's
  16.         8. Additional Info's
  17.  
  18.  
  19.  
  20. -------------------------------------------------------------------------
  21.                   CHAPTER 1, INTRODUCTION; THE FEATURES. 
  22. -------------------------------------------------------------------------
  23.  
  24. What is DEX ?
  25. DEX is a Compiler-Language, like C, Modula2, GfaBasic, Pascal etc. it
  26. features a similar programming structure and programming possibilities as
  27. above languages. Yet you'll have to consider that DEX as to offer a lot
  28. more, and, on the other hand, some aspects of the language are less
  29. flexible.
  30.  
  31. NEW FEATURES ADDED FROM v1.10 TO v1.15
  32. - DataType STRING, together with 14 functions to modify strings,
  33.   as StrAdd(), StrCmp(), Instr(), ReadStr(), Val(), StrCopy() etc.
  34. - 16 very handy miscelanious functions to make life easier: a.o.
  35.   OpenW(), OpenS(), Gadget(), FileLenght(), MouseX() etc.
  36. - Various small enhancements and bug fixes, like:
  37.   flexible comments /* */ and Constants TRUE, FALSE and NIL,
  38.   interrupting compilation by pressing both mousebuttons.
  39. - New example sources.
  40.  
  41. Dex Features:
  42. - Possibility of clear program structure (like f.e. Pascal and Gfa, no
  43.   C-spaghetti).
  44. - Short Executables; small to medium size DEX-sources will compile nearly
  45.   always compile to less than 1K, where above languages will need nearly
  46.   always more than 5K. (examples: the program given as an example with
  47.   the WRITE statement in the reference section would compile into an
  48.   executable of ± 300 bytes, the code of a complete vectordemo was done in
  49.   ± 1300 bytes, and a shell in ± 500 bytes. All inclusive hunks,
  50.   reloc-tables, opening of librarys etc.) 
  51. - Clear assembly source output: DEX generates fully commented assembly
  52.   source, in which you will be able to find all the variables you used,
  53.   and compare the code-generation directly to the DEX-source.
  54. - Direct access of all routines of EXEC, DOS, INTUITION, GRAPHICS and MATH,
  55.   without ANY includefiles and without opening ANY library. All 
  56.   customchip registers can adressed by their name, without ANY include.
  57. - Advanced features like Global/Local variables, easy calling of 
  58.   procedures and libraryroutines with return values, inline assembly
  59.   code, use of registervariables.
  60. - Faaast executables, extensive use of registers, fast parameter passing,
  61.   smart solutions for local variables and structs, quick optimization,
  62.   pc relative branching and adressing, special HYPER optimize mode for
  63.   loops and other instuctions where every clockcycle counts.
  64. - Easy to manage development system: just one compiler will do the job,
  65.   no 5 meg of includes, linkfiles, objects, optimizers, profilers etc.
  66.   All instructions needed for writing a substancial program integrated
  67.   in the compiler.
  68.  
  69.  
  70. What is shit about TurboDEX? (still in this version, that is.)
  71. - some things haven't been implemented.
  72. - some errors which you might make while programming are not recognised,
  73.   and will be compiled, since no things like stack-overflow checking
  74.   are implemented.
  75. - Its mosly faster than above languages, but still not optimized enough.
  76. - it doesn't do any type-checking, so things like dividing a CHAR
  77.   variable by a LONG, or messing up pointers to wrong memory-area's
  78.   are not flagged by the compiler.
  79. - The compiler can be *very* slow sometimes
  80. - The development system is not adequate for big app's.
  81. - kick 2.0 compatible but not 2.0 specific (generates 1.2-and-up code).
  82. - It's not idiot-proof.
  83.   
  84. Generally, DEX gets you ASSEMBLY quality performance an size executables,
  85. with BASIC effort. But the prize to pay for this that the programmer
  86. needs to know what he's doing. That's why this language is not ideal
  87. for beginners, but more appropriate for advanced coders who want to
  88. write a high performance util with minimum effort.
  89.  
  90. If you're eager to see what a DEX-source looks like, browse through
  91. the drawer with examples, kick-ass with 'HelloWorld.dex', then check
  92. out the other small sources. For your convenience here's some example:
  93.  
  94. ' oh look, it's my first DEX program! 
  95.  
  96. PROC main()
  97.   WRITE 'Hello, World!\n'
  98. ENDPROC
  99.  
  100. ' well, that was exiting, wasn't it? hmmm?
  101.  
  102.  
  103. -------------------------------------------------------------------------
  104.                        2. INSTALLATION AND RUNNING
  105. -------------------------------------------------------------------------
  106.  
  107. How to work with TurboDEX.
  108. First of all: all you really need is the compiler 'DEX'. just type
  109. something like:
  110.  
  111. DEX [-opts] <sourcefile>
  112.  
  113. example:
  114.  
  115. DEX:> dex -a helloworld
  116.  
  117. the compiler will take a pure ascii file with the name 'HELLOWORLD.DEX'
  118. as input in the current directory (this file contains some dex program
  119. you wrote), and will produce a file 'HELLOWORLD.S' as output (this file
  120. contains the assembly language translation from your DEX-source).
  121. The -a flag will cause DEX to invoke A68k and Blink straight away, to
  122. assemble and link the .S file..
  123. Now type:
  124.  
  125. DEX:> HELLOWORLD
  126.  
  127. Hello, World!
  128.  
  129. DEX:>
  130.  
  131. If you don't use the -a flag, you'll have to assemble by hand. Almost
  132. any assembler will do, supported are A68k and DEVPAC (tm).
  133. Compile with an assembler like A68K and link it with for example Blink:
  134.  
  135. Dh0:> A68K HELLOWORLD.S
  136. Dh0:> BLINK HELLOWORLD.O
  137.  
  138. Another example:
  139.  
  140. Dh0:> dex -flgr
  141.  
  142. This will enable you to pick your source by means of a file-requester,
  143. dex will generate a list-file, invoke Devpac's GENAM instead of the
  144. A68k/Blink duo, and execute your program afterwards.
  145.  
  146. Above is all you need.
  147.  
  148. Additional suggestions:
  149. Best you shove DEX into your C: dir next to A68K and BLINK.
  150. You may want to make Genam or Blink resident to speed up the process,
  151. and if don't own a HD, copy DEX to ram: so you can 
  152. Compile-Assemble-Link-Run without disk Access.
  153. NOTE: DEX outputs code suitable for A68K, so if you'd like to use
  154. some other Assembler, you could be forced to make some minor changes.
  155. (see -o option).
  156.  
  157. CommandLine Options:
  158. Executing DEX with nothing following it will result in DEX opening
  159. a window, where you can enter the commandline at the 'IN>' prompt.
  160.  
  161. options:
  162. ?   Display a 'usage:' and some info
  163. -a  If compiling succeeded, invoke A68K and BLINK from the compiler.
  164.     NOTES: both need to be in the search-path (i.e: mostly C: or the
  165.     active directory). this will need c:run (<2.0) and some free-memory.
  166. -c  Don't add comments to assembly source (because you're not interested
  167.     in the generated code anyway), makes file smaller.
  168. -f  Pops up a filerequester to let you choose a source to compile
  169.     instead of having to enter it at the commandline.
  170. -g  Have GENAM (part of the Devpac (tm) assembler) assemble and
  171.     link your program. Includes -o, excludes -a.
  172. -l  Produce a list file named <source>.LIST, containing statistical
  173.     info's about the program, the compiler-status, and lists of
  174.     identifiers, procedures etc.
  175. -o  Generate assembly source for any other assembler than A68k.
  176. -r  Run the executable after being generated. needs -a or -g
  177. -s  Try to generate code that is more reliable, but slower. The compiler
  178.     will insert extra intructions to do extending of wrong-size variables,
  179.     and make some extra checks. This option must only be used for
  180.     test-purposes. Not guaranteed to help.
  181. -t  Don't compile file at the command line, but internal test-source
  182.     instead (for test-purposes only).
  183.     
  184. NOTE: options are case-INsensitive, may be put anywhere on the commandline,
  185. and can be but together. so 'DEX -c test -A' has the same effect as
  186. 'DEX -ac test'.
  187.  
  188. NOTE2: Genam may act weird sometimes due to the fact that it expects being
  189. run from devpac when it isn't run run from a shell. if this bothers
  190. you, write a small script to run dex and genam, and leave -g.
  191.  
  192. Ok. Now over to the real stuff:
  193.  
  194. -------------------------------------------------------------------------
  195.                          3. THE LANUAGE IN GENERAL
  196. -------------------------------------------------------------------------
  197.  
  198. Procedures.
  199. All programming instructions are gathered in modules, called PROCs.
  200. The most important of these is the procedure PROC main() which always
  201. has to be part of a program (it doen't have to be the first procedure).
  202. this is the actuall program, where all variables are global. Other
  203. procedures can be added, that can have own (local) variables. These
  204. procedures can be called with or without parameters, like: 
  205. 'VOID getpicture(rastport,x+4,y/8)' 
  206. Procedures cannot be called recursively.
  207.  
  208. Loops.
  209. Lots of loops are supported, like FOR ... ENDFOR, WHILE ... ENDWHILE and
  210. some others. These can be nested infinetely (well, nearly).
  211.  
  212. Variables.
  213. At the moment 11 types of variables are supported:
  214. - LONG, a 32 bit wide integer variable, can hold any value from 
  215.   somewhat less than -2.14 to a little more than 2.14 milliard. this
  216.   is the most used variable since all addresses are kept in these,
  217.   most system routines expect longints, and nearly all calculations
  218.   are done in 32 bit.
  219. - INT, a 16 bit variable, keeps values from -32k to +32k. Used with
  220.   multiplies/divides.
  221. - CHAR, an 8 bit variable, most used with texts, and other small data.
  222.   range 0 to 255.
  223. - STRING, defines a string that may be modified, and used especially
  224.   for complex string manipulations. example:
  225.   DEF s=100:STRING
  226.   s may now be modified by special string functions. see chapter
  227.   on (string-)functions for more info.
  228. - REGLONG, REGINT and REGCHAR. These are the same ase those three described
  229.   above, with some small differences: - max. 6 of them can be used per
  230.   module, - 680x0 registers are used for their storage. 
  231.   The advantage of these is mainly their speed, as wel as the smaller and
  232.   better code they produce. They are best used with DOWN loops, and 
  233.   everywhere you need to have a certain part of your program to be as
  234.   faaast as possible.
  235.   NOTE WELL: these may only be declared with LOCAL
  236. - ARRAY and ARRAYCHIP. These are simple implementations of arrays, and 
  237.   function as CharArray only. They are defined as variable, and the
  238.   variable (compatible with LONG) contains a pointer to the array.
  239.   ARRAYCHIP is the version of ARRAY where the array is forced to 
  240.   chipmem. (for the 'insiders': BSS_c ).
  241. - CUSTOMREGS. all customregs can be used as variable. Just type the 
  242.   official name in capitals, like DMACON. this enables lines like:
  243.   AUD0LEN := samplelen/2   or even   COLOR00 := VPOSR*VHPOSR
  244.   its up to you to see which registers you can read or write.
  245. - ABSOLUTE, if you would write or read absolute addresses, you can
  246.   use a value (specifying the adress) between [], following the variable-
  247.   name in the definition, like: sysbase[4]:LONG, would enable you to
  248.   use sysbase as an absolute variable. Like this you can specify a
  249.   variable as part of a STRUCT, which provides extremely flexibel
  250.   programming, like: depth[newscreen.8]:INT
  251.  
  252. all these variables (except for the CustomRegs) have to be defined before
  253. use. See DEF in the reference section for more info's.
  254.  
  255. Other parameters.
  256. these can be used as value only.
  257. supported in this version are:
  258. - Values: dependent on the instruction you use, values like 4, 100,
  259.   4543836, $ff, $c00000, %101110 etc. can be used.
  260. - Adresses of labels and STRUCTS. you may need to now the address of a
  261.   label or stuct in your program. e.g. if somewhere in your program is
  262.   something like 'PROC text()', 'STRUCT text' or 'text:' the address could
  263.   be obtained with  adr := {text}  (use {} with the labelname).
  264. - a constant. currently, you can't define them yourself. only these are
  265.   available: TRUE (=-1), FALSE (=0), NIL (=0)
  266. - A text string. in the current version, strings that can be altered
  267.   are not supported. Though, you may give a string between '' as a
  268.   parameter. if the string is one character long, the ascii code will
  269.   be passed: c := 'A' equals c := 65 . If the string is longer, however,
  270.   the address of the string is passed, thus enabling flexible programming
  271.   were routines need the address of a textstring, for example:
  272.   VOID Text(rast,'Hello There !',LEN). LEN is a systemvariable, always
  273.   containing the lenght of the last string used. In the string you
  274.   may use the following codes:
  275.   \n    a return + linefeed (ascii 10 and 13)
  276.   \a    an apostophe, the one you need for enclosing the string
  277.   \t    insert a TAB (9)
  278.   \f    a linefeed (ascii 10)
  279.   \e    insert an escape-code (27), '\e[' will work as CSI.
  280.   \0    a null byte (not often needed, as all strings in DEX
  281.         are terminated with a '0').
  282.   \\    a backslash.
  283.         example: 'this: \a\\\a is a backslash \n\0'
  284.         Additionally, following codes may be used only when using a
  285.         string as part of a WRITE-statement:
  286.   \d    print out a LONG as decimal.
  287.   \h    print out a LONG as hexadecimal
  288.   \c    print out a LONG as character
  289.   \s    print out a 0-terminated string at address.
  290.   \w<x> sets minimum width for print, rest will be padded with spaces.
  291.   \z    pad with zeroes instead of spaces.
  292.   \m<x> sets maximum width for strings.
  293.   \l    put data to the right of the field (default).
  294.   \r    put data to the left in the field instead of to the right.
  295.         example:
  296.         WRITE 'some results: \z\w8 $\h \c.',65535,65
  297.         will print:
  298.         some results:  $0000FFFF A.
  299.   note: changes to print-formatting made with \w\z\m\l\r are only
  300.         valid within one WRITE-statement, they are reset to default
  301.         values at the start of the next statement.
  302. - A string as integer value. you may use strings of lenght 1-4 between
  303.   double quotes ("") to, for example, quickly compare short strings:
  304.   
  305.     IF {buffer}="FORM"               and          a := "A"
  306.  
  307.   are equal to
  308.  
  309.     IF {buffer}=$464F524D            and          a := 65
  310.  
  311.   The first character is stored in the MSB of the LONG. If only
  312.   one character is supplied, it is stored in the LSB.
  313.       
  314.  
  315. Parameters needed;
  316. mostly a parameter could be one of 2 different types, in the description
  317. of the commands that follows specified as var or exp.
  318. var = parameter that must be a variable. examples;
  319.       a, count, COLOR01, etc.
  320. exp = parameter that can be a variable, a value, or an expression (a
  321.       combination of more aspects). examples;
  322.       1, 200, $ff, a, DMACON, count+3/a-2000
  323.       these can be all mentioned above, including combinations.
  324. For example, the parameter of FOR that is the counter would be a var,
  325. and the two parameters specifying the range could be any exp(ression).
  326.  
  327. Expressions.
  328. as stated above, everywhere an instructions needs a parameter that is
  329. is an exp, you can use any of these operators with variables/values mentioned:
  330. -,+      minus and plus, no restrictions.
  331.          examples: 3+a, 60-{text}+$ff
  332. /,*      divide and product, these are always done 16bit wide, watch
  333.          carefully when using them. examples: a/20, counter*256.
  334.          for 32bit operations, see MUL() and DIV().
  335. &,^      AND and OR, used only as mathematical, not logical operators.
  336. =,<,>,?  comparisons. in the current version they are only usefull with
  337.          IF and WHILE. They need to be the last operator used.
  338.          In order: equal, smaller than, bigger than or equal, unequal.
  339.          examples: a=3, {data}-1024>$c00000, flag?0, 3*b+a
  340. IMPORTANT: in the current version of the compiler, expressions are compiled
  341. in the same order as written in the sourcecode, and () are not supported.
  342. thus, a+(3*b) shouldn't be written as a+3*b, but 3*b+a, otherwise a+3 would
  343. be calculated first, instead of 3*b. same goes for comparison (!) operators.
  344.  
  345. Labels and remarks.
  346. labels stand on their own line.
  347. a label is any string followed by a ':' and can be used only to point at
  348. instructions, not structs etc. (see above) example:
  349. startofprogram:
  350. when you program very structured, you won't need labels.
  351. two types of remarks are supported: remarks that start with a ' and
  352. stand on their own line. f.e.:
  353. ' Here the screen is setup
  354. /* or remarks that may be anywhere within the source, also on multiple
  355.    lines (not nested), as around this sentence  */
  356.  
  357.  
  358. Syntax.
  359. first of all, the only place where spaces are obigatory, is after an
  360. instruction keyword: WHILE<space>a=3
  361. furthermore, the whole language is case sensitive.
  362. uppercase: keywords, customregisternames
  363. lowercase: variablenames, labelnames, procnames, structnames
  364. both     : systemcallnames, Dex additional functions.
  365.            every part of the name starts of with an uppercaseletter,
  366.            like: VOID WindowToFront(), VOID OpenW()
  367.  
  368. Startup options.
  369. optional keywords about what sort of startup-code TurboDEX should
  370. generate, may be given between the brackets of PROC main() :
  371. ARG     The variables 'argadr' and 'argl' contain the command-line
  372.         passed to your program (both LONG).
  373. WB      Code will be added to start your program from workbench too.
  374.         NOTEZ BIEN: you need to supply a value for stdout
  375.         if you write a WB program that uses WRITE.
  376.         best is to open a CON:
  377. DETACH  makes a program auto-detaching, can be started from shell
  378.         without 'C:RUN'
  379. INIT    compiles no initcode at all, no opening of librarys etc,
  380.         for programs that need to be _VERY_ small (<200 bytes),
  381.         rarely usefull.
  382. example: PROC main(ARG)
  383. NOTE: it is not advisable to use more than one option at a time.
  384.  
  385. Build-In Variables:
  386. Presently, seven of them may be used: stdout, dosbase, graphicsbase,
  387. intuitionbase and mathffpbase (execbase is DEF sysbase[4]:LONG).
  388. When using these variables, code is genereated to provide a correct
  389. contents, and, when using a function from a library, the base is also
  390. defined. stdout contains the output filehandle (mostly the shell window),
  391. when using the WRITE statement: when it's 0, you can open a CON:, and
  392. put it's filehandle into the variable stdout. Furthermore, the variables
  393. argadr and argl (both LONG) may be used if the flag ARG is used
  394. in the header of main().
  395.  
  396.  
  397.  
  398. ------------------------------------------------------------------------
  399.                        4. STEP BY STEP TUTORIALS
  400. ------------------------------------------------------------------------
  401.  
  402. Assuming you copied DEX, A68K and BLINK to your C: directory, made
  403. a directory for storing your sources and the examplesources, and
  404. started up some editor to get things going, i will now give some small
  405. tutorials on DEX-programming.
  406.  
  407. Best you try to get the HelloWorld.dex program running first. This
  408. will give you a good impression on how the system works. load it in your
  409. editor to see what it looks like:
  410.  
  411. ' The HelloWorld program in DEX !
  412.  
  413. PROC main()
  414.   WRITE 'Hello, World!\n'
  415. ENDPROC
  416.  
  417. Now, change it to your needs, save it, and compile it with:
  418.  
  419. DEX HelloWorld -a
  420.  
  421. After all compiling has been done, check the directory the source is
  422. in. It should now contain two new files: HelloWorld.s and HelloWorld.
  423. I'll get back later on the contents of the .s file, now just execute
  424. the program by typing it's name. Please take note of the small size
  425. of the executable (i guess about 300 bytes).
  426.  
  427. You now used the basis of any dex program: the PROC main().
  428. this is the minimum of any program: you may add other procedures,
  429. which may have arguments and local variables. The WRITE instruction
  430. can be used for many more purposes than just writing string-contants:
  431. it can print variables in decimal, hexadecimal and ascii format,
  432. and nil-terminated strings. as an example we will now make a program
  433. that prints the starting address of the exec.library to the screen:
  434.  
  435. PROC main()
  436.   DEF sysbase[4]:LONG
  437.   WRITE 'execbase = $\h',sysbase
  438. ENDPROC
  439.  
  440. Here we do something new, we declare a global variable, like 'a'
  441.  
  442. DEF a:LONG
  443.  
  444. but now we state we would like to have it at a fixed address, $00000004.
  445. We can print out the contents of the variable sysbase by putting
  446. the formatcode '\h' (hexadecimal) in the outputstring, and the value
  447. following it.
  448.  
  449. I will now discuss some of the programs to be found in the directory
  450. with example sources to show how small programs could be developped.
  451. First here's the SHELL.DEX program:
  452.  
  453. /* TurboShell in TurboDEX */
  454.  
  455. PROC main(DETACH)
  456.   DEF window:LONG, buffer=60:ARRAY, a:REGLONG, text:REGLONG
  457.   window := Open('con:10/10/400/100/TurboShell v0.0\0',1006)
  458.   VOID Write(window,'Shell by $#%! in 1991. \aquit\a to stop.\n',LEN)
  459.   WHILE text?"quit"
  460.     VOID Execute(buffer,0,window)
  461.     VOID Write(window,'Turbo> ',LEN)
  462.     a := Read(window,buffer,59)
  463.     MCHAR buffer+a,0
  464.     text := MLONG(buffer)
  465.   ENDWHILE
  466.   VOID Close(window)
  467. ENDPROC
  468.  
  469. It's a very small program that show's clearly enough how to use some of
  470. the language's features. Here's a step-by-step explanation of how
  471. it works:
  472.  
  473. Because it's a small program, all code is gathered in one procedure,
  474. and we tell the compiler that we want to give the Shell-prompt back
  475. after our program is loaded with the DETACH option. Now we define
  476. a couple of variables for use in the program: in 'window' we will
  477. store the filehandle to our CON:-window, 'a' and 'text' are for use
  478. lateron and buffer is an array of 60 bytes, which we will use to store
  479. the commandline Note that 'buffer' is actually a variabele of the type
  480. LONG which contains a pointer to that array. Now we use Open() from
  481. the dos.library to open our console window, and we do not check if
  482. an error occurred, for the simplicity of the example. Note that you
  483. do not need include-files modules to be linked or whatever to be 
  484. able to use functions like Open, they're build in to the language.
  485. Now we use the dos.library Write() (not the DEX WRITE!) to output
  486. a message to it: We could have done this using WRITE, but the example
  487. is about system-functions. Now we come in a loop which we will only
  488. exit if 'text' is unequal to the (LONG-encoded) string "quit".
  489. In this loop, we will Read() something from the console, and then
  490. Exexute() it as a cli-command. Note that we use MCHAR (put a CHAR-sized
  491. value into memory) to terminate the string.
  492.  
  493. Here's a somewhat longer example to get the feeling of how things
  494. are done in DEX, COLORSCREEN.DEX
  495.  
  496. /* Open a screen and do something */
  497.  
  498. PROC main()
  499.   DEF rast:LONG,screen:LONG
  500.   DEF sx:REGINT, sy:REGINT
  501.   screen := OpenS(320,256,5,0,' TurboDEX Screen ')
  502.   rast := screen+84
  503.   IF screen?FALSE
  504.     MOUSE
  505.       DOWN sx,320
  506.         DOWN sy,256
  507.           VOID SetAPen(rast,sx*sy)
  508.           VOID WritePixel(rast,sx,sy)
  509.           JUMPMOUSE leave
  510.         ENDDOWN
  511.       ENDDOWN
  512.     ENDMOUSE
  513.     leave:
  514.     VOID CloseS(screen)
  515.   ENDIF
  516. ENDPROC
  517.  
  518.  
  519. We use the DEX functions new in v1.15 to open and close our screen:
  520. OpenW(), CloseS(). before we start plotting we have to be sure
  521. the screen was actually opened.
  522.  
  523. In the main program we enter the big MOUSE - ENDMOUSE loop which
  524. is very handy for demo-like programs like this one. it is accompanied
  525. by an extra JUMPMOUSE for faster exit. The inner loop draws the screen
  526. full of colourfull pixels. Note the VOID intruction: we're not interested
  527. in the returnvalues ( 'VOID' is like 'dummy:=' ), when calling the
  528. procedure screen(), we are: ENDPROC gives us the screenptr.
  529.  
  530. Now we will look at a complete utility in DEX, with errorchecks
  531. To make it usefull for everyday use: a three-column dir-command!
  532. DIRQUICK.DEX displays filelenght too and makes use of extended WRITE
  533. string-formatting.
  534.  
  535. /* nice directory command in dex ! */
  536.  
  537. PROC main(ARG)
  538.   DEF lock:LONG, info=260:ARRAY, ok:REGLONG, d:REGLONG, c:REGLONG
  539.   DEF dir:LONG
  540.   MCHAR argadr+argl-1,0
  541.   lock := Lock(argadr,-2)
  542.   IF lock?FALSE
  543.     ok := Examine(lock,info)
  544.     IF ok?FALSE
  545.       dir := MLONG(info+4)
  546.       IF dir>0
  547.         WRITE 'Directory of: \s\n',info+8
  548.         c := 0
  549.         WHILE ok?FALSE
  550.           ok := ExNext(lock,info)
  551.           INC 1,c
  552.           IF ok?FALSE
  553.             d := MLONG(info+124)
  554.             dir := MLONG(info+4)
  555.             IF dir>0
  556.               WRITE '\e[1;32m\w25\m25\l\s\e[0;31m',info+8
  557.             ELSE
  558.               WRITE '\w17\m17\l\s \r\w7\d',info+8,d
  559.             ENDIF
  560.             IF c=3
  561.               WRITE '\n'
  562.               c := 0
  563.             ELSE
  564.               WRITE ' '  
  565.             ENDIF
  566.           ENDIF
  567.         ENDWHILE
  568.         IF c?1
  569.           WRITE '\n'
  570.         ENDIF
  571.       ELSE
  572.         WRITE 'No Dir!\n'
  573.       ENDIF
  574.     ENDIF
  575.     VOID UnLock(lock)
  576.   ELSE
  577.     WRITE 'What ?!?\n'
  578.   ENDIF
  579. ENDPROC
  580.  
  581.  
  582. At every step in the program we check if an error may have occurred,
  583. and we put all the nested IF's into one procedure: after making the
  584. neccesary locks and examines, we read each entry, and put it directly
  585. on the screen, directory's and files each their own color for distinction.
  586. Those WRITE statements are good examples of somewhat more complex
  587. string/integer formatting. Note we keep track of the column we're in 
  588. with variable 'c'.
  589.  
  590. Here's short description of all other examples:
  591.  
  592. DIRSORT.DEX     An extented version of DIRQUICK.DEX, does a very
  593.                 slow bubble sort on the entries before displaying, and
  594.                 separates the directories from the files. can only read
  595.                 dir's with less than 400 entries (changeable).
  596. ASLREQ.DEX      a demo of how non-DEX-standard-kick-2-libraries may be 
  597.                 used: it puts up the ASL-filerequester, and checks
  598.                 nicely if you have KICK2, if it could open the library etc.
  599. PLAYSAMPLE.DEX  Show's how the buil-in hardware-register variables
  600.                 can be used to play a beep.
  601. COPPER.DEX      Show's the ease of copper-programming from DEX
  602. NEWWINDOW.DEX   Opens a intuition-window and output's a text it.
  603. ARG.DEX         Show's how to handle commandline arguments from DEX.
  604. SPEED.DEX       Proggie to show off DEX's optimed loops.
  605. RESIDENT.DEX    Display's all exec resident modules. Shows how for example
  606.                 system lists can be dumped.
  607. VECTOR.DEX      A vectorDemo in DEX that rotates the word 'TurboDEX' on
  608.                 the screen in three colours, using the graphics.library,
  609.                 double-buffering and a precalculated-coordinate list
  610.                 in the file VECTOR.BIN. If you want to compile
  611.                 this program, make sure the INCLUDE statement in the
  612.                 source points to where you have the .BIN file.
  613.  
  614. What's new in v1.15: (except the update of above examples)
  615.  
  616. MEM.DEX         a small utility to let you view any memory area
  617.                 with hex and asciidump as in a monitor, but now from
  618.                 a shell. very handy for debugging.
  619. QUICKLAUNCH.DEX a complete application launching utility in DEX.
  620.                 reads names of app's from a configfile in S:, then
  621.                 put's them in a window with DEX powerfull new
  622.                 GadGet() function. nice utility.
  623.  
  624. Furtermore in the directory PDexamples, you will find sources written
  625. by authors other than me, distributed as PD. currently this is only one.
  626. Send your sources to me for inclusion in this directory.
  627.  
  628.  
  629.  
  630. -------------------------------------------------------------------------
  631.                5. ALPHABETICAL DESCRIPTION OF INSTRUCTIONS
  632. -------------------------------------------------------------------------
  633.  
  634. -----------
  635. AND, OR, NOT
  636. -----------
  637. syntax:      AND value,variable
  638.              OR value,variable
  639.              NOT variable
  640. description: Performs logical and, or and not on a variable.
  641.              NOTE: AND and OR  are also available as operators in an
  642.              expression (&,^).
  643. example:     AND $ff,c
  644.              NOT x
  645.  
  646. -----------
  647. ASM, ENDASM
  648. -----------
  649. syntax:      ASM
  650.              ENDASM
  651. description: all following this statement until ENDASM will not be compiled
  652.              by the compiler, and is put unchanged into the output file,
  653.              thus enabling inline assembly. if registers D2-D7 are used,
  654.              these should be put on the stack first. Make sure you use
  655.              distinct labels: best way is to prefix them.
  656. example      ASM
  657.                moveq #0,d0
  658.              ENDASM
  659.  
  660. -----------
  661. CALL
  662. -----------
  663. syntax:      CALL address, paraddress, returnvar
  664.              CALL base[offset], paraddress, returnvar
  665. par:         address = any memory location that is the start of a routine
  666.              base = base address of a library
  667.              offset = offset from a librarybase, like -552
  668.              paraddress = pointer to memory chunk of 14 longwords,
  669.              containing the parameters to a routine, in d0-d7/a0-a5 order.
  670.              returnvar = variable to put the returnvalue in
  671.              NOTE: both paraddress and returnvar are optional.
  672. description: this instruction enables you to call any assembly language
  673.              subroutine, and in particular librarycalls that are not
  674.              part of the DEX set.
  675.              see the ASLREQ.DEX source for a good example.
  676. example:     ' assuming you have an initialized variable called 'aslbase':
  677.  
  678.              CALL aslbase[-30],,reqadr
  679.  
  680.              ' this will call AllocFileRequest() from the asl.library 
  681.              ' reqadr may contain 0
  682.  
  683.  
  684. -----------
  685. CMOVE, CWAIT, CSKIP, CPART, CSTOP
  686. -----------
  687. syntax:      CMOVE value,customreg
  688.              CWAIT rastline,rastpos
  689.              CSKIP rastline,rastpos
  690.              CPART
  691.              CSTOP
  692. par:         customreg = valid name for a customchip register, like: BLTSIZE
  693.              rastline = beam y position (0-255)
  694.              rastpos = beam x position (0-$E0)
  695. description: Instructionset to code the copper coprocessor. these
  696.              instructions need to be gathered in a CHIPSTRUCT
  697.              See your Hardware Reference Manual for more information on
  698.              functioning of these instructions. CSTOP designates the 
  699.              end of a copper-list, CPART needs to precede any intructions
  700.              that are to be executed after rasterline 255.
  701. example:     ' Split screen in two colors and be very rude to multitasking;
  702.  
  703.              PROC main()
  704.                COP2LCH := {coplist}
  705.                INTENA := $4000
  706.                MOUSE
  707.                ENDMOUSE
  708.              ENDPROC
  709.  
  710.              CHIPSTRUCT coplist
  711.                CMOVE $fff,COLOR00
  712.                CWAIT 80,$01
  713.                CMOVE $f00,COLOR00
  714.                CSTOP
  715.              ENDCHIPSTRUCT
  716.  
  717. -----------
  718. DEC, INC
  719. -----------
  720. syntax:      DEC value,variable
  721.              INC value,variable
  722. description: Substracts or adds the value (-8 to 8 excluding 0)
  723.              to the indicated variable.
  724. example:     INC count
  725.  
  726. -----------
  727. DEF, LOCAL
  728. -----------
  729. syntax:      DEF varname:TYPE [, ... ]
  730.              LOCAL varname:TYPE [, ... ]
  731. par:         type = any of the types of variables discussed in the above 
  732.              section of variabletypes (like LONG, ARRAY etc.)
  733.              varname = any string, signifying the name of the variable. may
  734.              be followed by = with a value (LONG, INT, CHAR only) to 
  735.              initialize it before use (default = 0). Using = with ARRAY
  736.              signifies the size of the array (like string=100:ARRAY).
  737. description: declares a variable before use, where DEF defines the
  738.              variables that can be used in any module (global), and LOCAL those
  739.              which can only be used in one module (local).
  740. example:     DEF adr:LONG, sign=25:CHAR, count:REGINT, string=256:ARRAY
  741.              LOCAL item[data.6]:INT, picture=10240:ARRAYCHIP
  742.  
  743. -----------
  744. DIV, MUL
  745. -----------
  746. syntax:      var := MUL(exp,exp)
  747.              var := DIV(exp,exp)
  748. description: MUL and DIV are 32 bit substitutes for the * and / operators.
  749.              The 68000 processor doesn't support 32 bit multiplication and
  750.              division, only 16 bit. dex compiles * and / using 16 bit,
  751.              for speed reasons, and tries to use 32 bit shifts when
  752.              possible. Mostly this isn't a problem, but when it is,
  753.              the slower DIV and MUL routines can be called to use
  754.              the full 32 bit.
  755.  
  756. -----------
  757. DOWN, ENDDOWN
  758. -----------
  759. syntax:      DOWN counter,loops
  760.              ENDDOWN
  761. par:         counter = (var) variable decreased by the loop
  762.              loops = (exp) number of times loops should be executed
  763. description: this is a simple FOR loop. the counter will be decreased
  764.              to zero, f.e. if you specify 100 for loops, the counter will
  765.              go from 99 to 0. the must end with an ENDDOWN.
  766.              NOTE: Because the only reason to use DOWN over FOR is
  767.              speed, it can only be used with REG variables (i.e. REGLONG).
  768. note:        do not use DOWN for loops that need to be done only once
  769.              or less.
  770. example:     DOWN count,1000000
  771.                ' fast loop here
  772.              ENDDOWN
  773.  
  774. -----------
  775. ENDPROC
  776. -----------
  777. syntax:      ENDPROC returnvalue
  778. par:         returnvalue = (exp) result of the PROC
  779. description: marks the end of a procedure and returnes a value to the
  780.              whatever called it. Default is zero
  781. example      see PROC example 2
  782.  
  783. -----------
  784. EXIT
  785. -----------
  786. syntax:      EXIT returnvalue
  787. par:         returnvalue (exp) = returncode for dos
  788. description: exits program at any point in the program.
  789. example:     EXIT 5
  790.  
  791. -----------
  792. FOR, ENDFOR
  793. -----------
  794. syntax:      FOR counter,start,end [,step]
  795.              ENDFOR
  796. par:         counter = (var) the variable that counts the loops
  797.              start = (exp) begin value of counter
  798.              end = (var or value) value for the loop to end with.
  799.              step = a value between 8 and -8 (excluding 0), default 1
  800. description: The loop will be executed as many times as specified by 
  801.              start and end. meanwhile, the counter is being increased
  802.              with every loop. as standard, the counter will be increased
  803.              by 1, specifying a step changes this.
  804. example:     FOR counter,0,319,2
  805.                VOID Move(rast,counter,0)
  806.                VOID Draw(rast,counter,255)
  807.              ENDFOR
  808.  
  809. -----------
  810. GOTO
  811. -----------
  812. syntax:      GOTO labelname
  813. description: continues the execution of the program within one module
  814.              at the place of the label.
  815. example:     IF a/20=3
  816.                GOTO someplace
  817.              ENDIF
  818.              ' rest of the program
  819.              someplace:
  820.  
  821. -----------
  822. IF, ELSEIF ELSE, ENDIF
  823. -----------
  824. syntax:      IF equation
  825.              ...
  826.              [ ELSEIF equation ]
  827.              ...
  828.              [ ELSEIF equation ]
  829.              ...
  830.              [ ELSE ]
  831.              ...
  832.              ENDIF
  833. par:         equation (exp) = expression to be equated.
  834. description: the programblock between IF and ENDIF will only be executed
  835.              if the expression is TRUE. if it is FALSE, however, it will
  836.              be skipped, and an ELSEIF block may be executed if that
  837.              equation is TRUE. If an ELSE block is present, it will only be
  838.              executed if all the other IF's were FALSE.
  839. example:     IF a>1000
  840.                WRITE 'hey dude, \d is a little too much!!!\n',a
  841.              ELSEIF a<0
  842.                WRITE 'what about that?\n'
  843.              ELSE
  844.                WRITE 'that's more like it!\n'
  845.              ENDIF
  846.  
  847. -----------
  848. INCLUDE
  849. -----------
  850. syntax:      INCLUDE filename
  851. description: Includes any binary file into the program. Statement
  852.              needs to be part of a STRUCT to be accessed properly.
  853.              filename doesn't need quotes.
  854.  
  855. -----------
  856. JUMPMOUSE
  857. -----------
  858. syntax:      JUMPMOUSE label
  859. description: If the leftmousebutton is pressed at the moment this
  860.              instruction is executed, execution of the program will be
  861.              continued at <label> (only within one module).
  862.  
  863. -----------
  864. LONG, INT, CHAR
  865. -----------
  866. syntax:      LONG value1, value2, ...
  867.              INT value1, value1, ...
  868.              CHAR value1, value2, ...
  869. par:         value = any number like 4, 100, $c00000 etc. additionally,
  870.              with CHAR you may use strings, like: CHAR 'hello\0', and with
  871.              LONG you may use the adresses of programlabels, like:
  872.              LONG vectordata .
  873. description: with these statements you can put data of the appropriate
  874.              format into your program. they are only usefull within a
  875.              struct.
  876. example:     anylabel:
  877.              structadr := {anystruct}
  878.              STRUCT anystruct
  879.                INT 0,10240,512
  880.                LONG $c00000,anylabel,4
  881.                CHAR 0,25,'anystring\n\0',34,227
  882.              ENDSTRUCT
  883.  
  884. -----------
  885. LOOP, ENDLOOP
  886. -----------
  887. syntax:      LOOP
  888.              ENDLOOP
  889. description: builds an infinite loop. Must end with ENDLOOP. be sure there
  890.              is an exit out of the loop.
  891. example:     LOOP
  892.                WRITE 'An everlasting loop\n'
  893.              ENDLOOP
  894.  
  895. -----------
  896. MLONG,MINT,MCHAR
  897. -----------
  898. syntax:      MLONG address,value
  899.                       or
  900.              value := MLONG(address)
  901. par:         address (exp) = any valid memory address, with MLONG and
  902.              MINT this needs to be at an equal address.
  903.              value (exp) = the value to be 'poked' into, or read from
  904.              that memorylocation.
  905. description: Commands similar to PEEK and POKE in basic, poke a longword,
  906.              word and byte respectively.
  907. example:     MCHAR $40000+a,b-1
  908.  
  909. -----------
  910. MOUSE, ENDMOUSE
  911. -----------
  912. syntax:      MOUSE
  913.              ENDMOUSE
  914. description: these make a loop that will be repeated as long as the
  915.              left mousebutton is not pushed.
  916. example:     MOUSE
  917.                VOID movesprites(x,y,3)
  918.                VOID playtune()
  919.              ENDMOUSE
  920.  
  921. -----------
  922. WRITE
  923. -----------
  924. syntax:      WRITE 'string'
  925. par:         'string' = any string of ascii signs, that may contain
  926.              codes with an '\' (see above for a discussion on strings
  927.              and codes).
  928. description: prints any string and/or integers etc. to standard output
  929.              (normally the cli/shell window); can be used to write to
  930.              files by saying:  stdout:=Open(...)  etc. 
  931. example:     PROC main()
  932.                WRITE 'Hello, World!\n'
  933.              ENDPROC
  934.  
  935. -----------
  936. PROC
  937. -----------
  938. syntax:      PROC name(par1, par2, ...) 
  939. par:         name,par = any normal string like 'dosomething', 'rastport'
  940.              these must be defined in this PROC as local variables.
  941. description: designates the beginning of a procedure. procedures should
  942.              not be nested, and the end of a procedure should always end
  943.              with an ENDPROC statement. Zero upto eight parameters can be
  944.              passed to localvars. Arguments for a PROC need to declared
  945.              as the first local variables in that module. for more info on
  946.              return values (as in example 2) see ENDPROC
  947.              Info on the main PROC can be found elsewhere
  948. example 1  : PROC screenflash()
  949.                VOID DisplayBeep(0)
  950.              ENDPROC
  951. example 2  : result=addition(x,y)
  952.              ...
  953.              PROC addition(value1, value2)
  954.                LOCAL value1:LONG, value2:LONG 
  955.              ENDPROC value1+value2
  956.  
  957. -----------
  958. REPEAT, UNTIL
  959. -----------
  960. syntax:      REPEAT
  961.              UNTIL equation
  962. description: The block within REPEAT/UNTIL is repeated as long as the
  963.              truth for the equation holds. Thus, this loop will always
  964.              be executed atleast once: the UNTIL will jump to the
  965.              beginning of the loop if the equation is TRUE.
  966. example:     REPEAT
  967.                Read(fh,buf,10)
  968.              UNTIL {buf}="quit"
  969.  
  970. -----------
  971. SIZEOF
  972. -----------
  973. syntax:      size := SIZEOF(label)
  974. description: SIZEOF returns the size of the STRUCT indicated by the label.
  975. example:     see STRUCT
  976.  
  977. -----------
  978. STRUCT, ENDSTRUCT
  979. -----------
  980. syntax:      STRUCT structname
  981.              ENDSTRUCT
  982. description: this statemenent adds a struct to your program. it can be
  983.              anywhere in the program, since it will be compiled to a
  984.              place separate from the code. see description of LONG etc.
  985.              for more info's. The statements CHIPSTRUCT and ENDCHIPSTRUCT
  986.              function exactly the same way, but will be allocated in
  987.              chipmem (handy for copperlists, see CMOVE etc.).
  988. example:     a := SIZEOF(newscreen)
  989.              STRUCT newscreen
  990.                INT 0,0,640,256
  991.                LONG 0,0, ... etc.
  992.                CHAR 'WindowTitle\0'
  993.              ENDSTRUCT
  994.  
  995. -----------
  996. WHILE, ENDWHILE
  997. -----------
  998. syntax:      WHILE equation
  999. par:         equation = (exp) comparison to be equated.
  1000. description: the loop between WHILE and ENDWHILE is repeated as long as
  1001.              the equation is TRUE. the program will continue after
  1002.              ENDWHILE as soon as the equation is false. this loop must
  1003.              end with ENDWHILE.
  1004. example:     WHILE a/3+1 > 100
  1005.                a := a-1
  1006.              ENDWHILE
  1007.  
  1008.  
  1009.  
  1010. ------------------------------------------------------------------------
  1011.                         6. FUNCTION OVERVIEW
  1012. ------------------------------------------------------------------------
  1013.  
  1014. The 30 all new functions can be divided into 5 intuition, 3 mouse, 8
  1015. Dos/miscelanious programming functions and 14 string functions,
  1016. which will be discussed at the end.
  1017.  
  1018. ------------------------------------------
  1019. OpenW() OpenS() CloseW() CloseS() Gadget()
  1020. ------------------------------------------
  1021.  
  1022. wptr:=OpenW(x,y,width,height,IDCMP,wflags,title,screen,sflags,gadgets)
  1023.  
  1024. creates a window where wflags are flags for window layout
  1025. (like BACKDROP, SIMPLEREFRESH e.d, usually $F) and sflags are
  1026. for specifying the type of screen to open on (1=wb,15=custom).
  1027. screen must only be valid if sflags=15, else NIL will do.
  1028. gadgets may point to a glist structure, which you can easily
  1029. create with the Gadget() function, else NIL.
  1030.  
  1031. VOID CloseW(wptr)
  1032.  
  1033. closes that screen again. only difference from CloseWindow()
  1034. is that it accepts NIL-pointers.
  1035.  
  1036. sptr:=OpenS(width,height,depth,sflags,title)
  1037.  
  1038. opens a custom screen for you. sflags is again mostly 15.
  1039.  
  1040. VOID CloseS(sptr)
  1041.  
  1042. as CloseW(), now for screens.
  1043.  
  1044. glistvar:=Gadget(buffer,glist,id,flags,x,y,width,string)
  1045.  
  1046. This function to create a list of gadgets, which can then be put in your
  1047. window by giving them as an argument to OpenW(), or afterwards with
  1048. intuition functions like AddGlist().
  1049. buffer is mostly an ARRAY of atleast 120 bytes to hold all the structures
  1050. associated with one gadget, id is any number that may help you remember as
  1051. to which gadget was pressed when an IntuiMessage arrives.
  1052. flags are: 0=normal gadget, 1=boolean gadget, 3=boolean gadget that is
  1053. selected. width is width in pixels, that should be large enough to hold
  1054. the string, which will be auto-centered. glist should NIL for the first
  1055. gadget, and glistvar for all others, so DEX may link all gadgets.
  1056. example for three gadgets:
  1057.  
  1058. DEF buf=360:ARRAY, mygadget:LONG, wptr:LONG
  1059. mygadgets:=Gadget(buf,NIL,... )                 /* the 1st gadget */
  1060. VOID Gadget(buf+120,mygadgets,... )
  1061. VOID Gadget(buf+240,mygadgets,... )             /* any amount linked 2 1st */
  1062. wptr:=OpenW( ...,mygadgets)
  1063.  
  1064. See QuickLaunch.Dex for an example of these functions.
  1065.  
  1066.  
  1067. -------------------------
  1068. Mouse() MouseX() MouseY()
  1069. -------------------------
  1070.  
  1071. code:=Mouse()
  1072.  
  1073. gives you the current state of all 2 or 3 mousebuttons; left=1,
  1074. right=2 and middle=4. if for example code=3 then left and right were
  1075. pressed together.
  1076.  
  1077. x:=MouseX()      and     y:=MouseY()
  1078.  
  1079. enables you to read the mouse coordintes. these are always in highest
  1080. resolution (640x512, or even more), so you need to scale them if
  1081. your app works in a lower resolution.
  1082.  
  1083.  
  1084. ------------------------------------------------------------------
  1085. And() Or() Not() Out() Inp() KickVersion() Filelenght() SetTopaz()
  1086. ------------------------------------------------------------------
  1087.  
  1088. a:=And(b,c)    and    a:=Or(b,c)    and    a:=Not(b)
  1089.  
  1090. These work with the usual operations, boolean as well as arithmetical.
  1091.  
  1092. VOID Out(filehandle,char)        and        char:=Inp(filehandle)
  1093.  
  1094. Either write or read one single byte to some file or stdout
  1095. if char=-1 then an EOF was reached, or an error occured.
  1096.  
  1097. bool:=KickVersion(vers)
  1098.  
  1099. Will give TRUE if the kickstart in the machine your program is running
  1100. on is equal or higher than vers, else FALSE
  1101.  
  1102. len:=FileLenght(namestring)
  1103.  
  1104. let's you determine the lenght of a file you *may* wish to load, and
  1105. also, if it exists (returns -1 upon error/file not found).
  1106.  
  1107. VOID SetTopaz(rast,size)
  1108.  
  1109. let's you set the font of the rastport to topaz, just to be sure that
  1110. some custom systemfont of the user won't trash your window layout.
  1111. size is ofcourse 8, 9 or (11)
  1112.  
  1113.  
  1114. ----------------
  1115. String Functions
  1116. ----------------
  1117.  
  1118. Starting at v1.15, DEX has a datatype STRING. This is a string, from
  1119. now on called 'Dstring', that maybe modified and changed in size,
  1120. as opposed to normal strings, usually called 'Cstrings'. Dstrings are
  1121. downward compatible with Cstrings, but not the other way around, so if
  1122. an argument request a normal string, it can be either of them.
  1123. If a dstring is requested, don't use cstrings.
  1124. example on the usage:
  1125.  
  1126. DEF s=80:STRING, n:LONG          /* s is a dstring with a maxlen of 80 */
  1127. VOID ReadStr(stdout,s)           /* read input from the console */
  1128. n:=Val(s)                        /* get a number out of it */
  1129.   ... etc.
  1130.  
  1131. Note that all 14 functions will handle cases where string tends to
  1132. get longer than the maximum lenght correctly;
  1133.  
  1134. DEF s=5:STRING
  1135. VOID StrAdd(s,'this string is longer than 5 characters',TRUE)
  1136.  
  1137. s will contain just 'this '.
  1138.  
  1139.  
  1140. bool:=StrCmp(string,string,len)
  1141. compares two strings. len must be the number of bytes to compare,
  1142. or TRUE if the full lenght is to be compared.
  1143.  
  1144. VOID StrCopy(Dstring,string,len)
  1145. copies the string into the dstring. if len=TRUE, all will be copied.
  1146.  
  1147. VOID StrAdd(Dstring,string,len)
  1148. same as StrCopy(), only now the string is concatenated to the end.
  1149.  
  1150. len:=StrLen(string)
  1151. calculates the lenght of a string
  1152.  
  1153. len:=DstrLen(dstring)
  1154. returns the lenght of a dstring
  1155.  
  1156. max:=StrMax(dstring)
  1157. returns the maximum lenght of a dstring
  1158.  
  1159. VOID RightStr(dstring,string,n)
  1160. fills dstring with the n rightmost characters of a string
  1161.  
  1162. VOID MidStr(dstring,string,pos,len)
  1163. copies any number of characters (including all if len=TRUE) from
  1164. position pos in string to dstring
  1165. NOTEZ BIEN: in all string related functions where a position in a
  1166. string is used, the first character in a string has position 0,
  1167. not 1, as used in languages like BASIC.
  1168.  
  1169. value:=Val(string)
  1170. finds an integer encoded in ascii out of a string. leading spaces will
  1171. be skipped, and also hexadecimal numbers (1234567890ABCDEF) may
  1172. be read this way if they are preceded by a '$' sign.
  1173. Val()  returns -1 if the string did not contain an integer, or
  1174. the value was too sizy to fit in a LONG.
  1175.  
  1176. foundpos:=InStr(string1,string2,startpos)
  1177. searches string1 for the occurence of string2, possibly starting from
  1178. another position than 0. returned is the position at which the substring
  1179. was found, else -1.
  1180.  
  1181. newadr:=TrimStr(string)
  1182. returns the *address* of the first character in a string, i.e., after
  1183. leading spaces, tabs etc.
  1184.  
  1185. VOID UpperStr(dstring)     and      VOID LowerStr(dstring)
  1186. changes the case of a string. may also be used on cstrings if
  1187. these are part of your program's data, since the string is modified,
  1188. but not changed in size.
  1189.  
  1190. ok:=ReadStr(filehandle,dstring)
  1191. will read a string (ending in ascii 10) from any file or stdout.
  1192. ok contains -1 if an error occurred, or an EOF was reached.
  1193.  
  1194.  
  1195.  
  1196. ------------------------------------------------------------------------
  1197.                 7. ADVANCED PROGRAMMING AND LANGUAGE INFO'S
  1198. ------------------------------------------------------------------------
  1199.  
  1200. This chapter is about:
  1201.  
  1202. - DEX <-> Assembly conventions.
  1203. - Code generated by DEX / Optimizing.
  1204. - Debugging.
  1205. - EBNF overview of DEX syntax.
  1206. - DEX as a language concept / The future of DEX / All new EEX compiler.
  1207.  
  1208.  
  1209. To use the inline assembly feature without trouble, it's best to
  1210. know a few things about TurboDEX code-generation:
  1211.  
  1212. Register use: normally you may trash ALL (except A7, ofcourse!)
  1213. registers, since none are used to point at vital data during the
  1214. course of the program. However, REG variables are stored in D2-D7,
  1215. (starting with D7) so if you use these in your DEX code, you may not
  1216. trash these. Using REG-variables can also be a fine way to allocate
  1217. a register for permanent use in a PROC, for example:
  1218.  
  1219. PROC bla()
  1220.   LOCAL a:REGINT, b:REGLONG
  1221.   ...
  1222.   ASM
  1223.     ...  (use D6(=b), D7(=a) here)
  1224.   ENDASM
  1225.   ...    (use a,b here)
  1226. ENDPROC
  1227.  
  1228. In this module you could store something permanent in D6/D7, without
  1229. the danger of getting them trashed: DEX will preserve these registers
  1230. if they need to be used for a (system-)functioncall.
  1231. This is the sort of PROC-setup you'd be using to obtain very optimized
  1232. code.
  1233.  
  1234. D0-D1/A0-A1 may ofcourse be trashed by assembly as well as DEX code.
  1235. Functions like WRITE are likely to trash more address-registers than
  1236. just these.
  1237.  
  1238. Sharing local and global variables:
  1239. Each variable has a label that can be used to access DEX-variables
  1240. from within the inline assembler, they are build as folows:
  1241.  
  1242. ModuleName + 'var' + VariableName
  1243.  
  1244.           PROC bla()
  1245. Example:    DEF screen:LONG      gives EA:   mainvarscreen
  1246.             LOCAL a:INT                      blavara
  1247.           ENDPROC
  1248.  
  1249. note that global variables always have ModuleName = 'main'
  1250.  
  1251. if you want to have an overview of the each effective address
  1252. then compile your program with option -l, also have a look at the
  1253. source (the .s file) TurboDEX generates to get the idea.
  1254.  
  1255. Accessing of labels and arrays is just as easy:
  1256.  
  1257. PROC main()                 will yield:     proglabmain
  1258. DEF string=80:ARRAY                         arraylabstring
  1259. start:                                      proglabstart
  1260. STRUCT newscreen                            proglabnewscreen
  1261.  
  1262. If your program uses functions from a certain library, the base of
  1263. that library can be accessed by LibraryName + 'base' (f.e. dosbase).
  1264.  
  1265. Debugging hints:
  1266. Apart from debuggingmethods that may be used on any language/compiler,
  1267. following are specifically handy with DEX:
  1268. - expressions: as these are different from other other languages,
  1269.   it's very likely mistakes are made: check out the order of
  1270.   operators/comparison's, problems that may occur when using/comparing
  1271.   variables of different sizes (LONG/CHAR) etc.
  1272. - compile with -l to see if you possibly made errors in declaration
  1273.   of variables etc.
  1274. - check variables that contain pointers, as DEX does no type-checking
  1275. - throwing the assembly source through a source-level debugger will
  1276.   mostly indicate the problem :-) .
  1277.  
  1278. BNF overview of the language:
  1279. The compiler-builders under the readers may find it clarifying
  1280. to see some structural elements formalized (not complete): 
  1281.  
  1282. <program> ::= { <procedure> }
  1283. <procedure> ::= PROC <label> ( <definitionlist> )
  1284.         { <defstatement> | <localstatement> }
  1285.         { <statementblock }
  1286.         ENDPROC <exp>
  1287. <label> ::= <ident>
  1288. <variable> ::= <ident>
  1289. <ident> ::= <letter> { <character> }
  1290. <character> ::= <letter> | <digit>
  1291. <definitionlist> ::= <definition> { , <definition> }
  1292. <definition> ::= <variable> : <type> | 
  1293.         <variable> = <integer> : <type> |
  1294.         <variable> [ <absolute> ] : <type>
  1295. <type> ::= CHAR | INT | LONG | REGLONG | REGCHAR | REGINT |
  1296.         ARRAY | ARRAYCHIP
  1297. <integer> ::= <digit> { <digit> } |
  1298.         $ <hexcharacter> { <hexcharacter> }
  1299.         % 0 | 1 { 0 | 1 }
  1300. <absolute> ::= <integer> | <label> . <integer>
  1301. <defstatement> ::= DEF <definitionlist>
  1302. <localstatement> ::= LOCAL <definitionlist>
  1303. <statementblock> ::= { <statement> | <assignment> }
  1304. <exp> ::= <empty> | <expitem> { <operator> <expitem> }
  1305. <empty> ::=
  1306. <expitem> ::= <integer> | <variable> | '{' <label> '}' | " <ascii's> " |
  1307.         ' <ascii and format characters> '
  1308. <operator> ::= + | - | * | / | & | ^ | = | > | < | ?
  1309. <assignment> ::= <variable> := { <exp> | <procedurecall> |
  1310.         <function> | <systemcall> }
  1311. <procedurecall> ::= <label> <argumentlist>
  1312. <function ::= <keyword> <argumentlist>
  1313. <systemcall> ::= <amigasystemcall> <argumentlist>
  1314. <argumentlist> ::= () | ( <exp> { , <exp> } )
  1315. <statement> ::= { <structuralstatement> | <otherstatement> }
  1316. <structuralstatement> ::= <conditionalstatement> | <loopstatement>
  1317. <loopstatement> ::= <repeatstatement> | <forstatement> | ...
  1318. <repeatstatement> ::= REPEAT <statementblock> UNTIL <exp>
  1319. <forstatement> ::= FOR <variable> , <exp> , <integer>
  1320.         <statementblock> ENDFOR
  1321. <conditionalstatement> ::= <ifstatement> | ...
  1322. <ifstatement> ::= IF <exp> <statementblock> ENDIF |
  1323.         IF <exp> <statementblock> <elseblock> ENDIF
  1324. <elseblock> ::= { ELSEIF <exp> <statementblock> } |
  1325.         { ELSEIF <exp> <statementblock> } ELSE <statementblock>
  1326.  
  1327. Some definitions are missing, some things are simplified, and
  1328. of all instructions only a few are taken as an example. Just
  1329. to give the reader a view on the matter.
  1330.  
  1331.  
  1332.  
  1333. DEX as a language concept.
  1334. As you might have noticed, DEX is not a complicated language when
  1335. it comes to structural and typological elements. It belongs to
  1336. a family of three languages sofar, and is derived from the language E,
  1337. which inturn has mostly been influenced by Modula2 and some C.
  1338. In DEX only the fundamentals of E are left, nearly all advanced features
  1339. of the language are not contained in DEX, and DEX has few enhancements,
  1340. some as replacement of the proffessional features in E, others just
  1341. Amiga-specific add-ons.
  1342.                                E
  1343.                               / \
  1344.                              /   \
  1345.                             /    EEX
  1346.                            /
  1347.                          DEX
  1348.  
  1349. Another language in the family, also derived from E, is EEX. It
  1350. stands much closer to the original E language definition, and is
  1351. richer in structure. EEX stands for 'Easy E Instruction Code Set'.
  1352. Very worthwhile noting here is that a Amiga-specific EEX compiler
  1353. is being devellopped right now, and most important features of
  1354. this all new compiler are:
  1355. - about 40x (no joke!) the speed of the Dex compiler.
  1356. - doesn't generate assembly source, but executables straight away.
  1357. - does include Compiler, Linker and Assembler in one program,
  1358.   may even include Editor, Debugger and Monitor.
  1359.  
  1360.  
  1361. Import characteristics of E (and to some extend, also DEX and EEX)
  1362. as opposed to typical influences such as Modula2 (and some C) are:
  1363.  
  1364. 1. The Principle of True Inline Assembly:
  1365.    As no higher programming language can be an 'ideal' programming
  1366.    language, because only Assembly is, E has the feature of true
  1367.    inline assembly: assembly instructions are part of the language,
  1368.    and are equal to E instructions when it comes to using identifiers
  1369.    etc. Note that DEX has this feature only partly
  1370. 2. The Principle of System-Integration:
  1371.    the E language has OS-specific features in the core of the language.
  1372.    Because of 1 and 2 principle 3 automatically holds:
  1373. 3. The Principle of Non-Portability:
  1374.    Languages like DEX and EEX derived from E are designed to be non-
  1375.    portable: Programs should use machine-specific features (in this
  1376.    case AmigaOs 1.2 and up) for highest quality app's.
  1377. 4. The Principle of the Typeless Variables:
  1378.    E is Typeless. Types, as do exist in DEX, are gathered to one,
  1379.    as for example in EEX, where all types are LONG.
  1380.  
  1381. So, Those portability-lovers among you programmers might just as
  1382. well copy this distribution to NIL:. Note that rumours go that
  1383. a portable interpreter version of E is to appear on all well known
  1384. platforms.
  1385.  
  1386.  
  1387.  
  1388. ------------------------------------------------------------------------
  1389.                           8. ADDITIONAL INFO'S
  1390. ------------------------------------------------------------------------
  1391.  
  1392. TurboDEX Compiler v1.15 released as DonationWare in june 1992,
  1393. update from v1.1
  1394.  
  1395. Together with this distribution you will find A68k, Blink and their docs,
  1396. see those for distribution contraints. Thanx go to Charlie Gibbs (A68k)
  1397. and The Software Distillery (Blink).
  1398.  
  1399. NOTE to future DEX coders: people that use DEX more than occasionally
  1400. and get stuck may count on full support by me, the compiler author. Send 
  1401. your unsolvable problems or requests for hints/tips/tricks/enhancements
  1402. to me (i prefer electronic above paper mail). Also sources of for example
  1403. completed utilities in DEX may be send for inclusion in a library of
  1404. DEX-sources to be distributed with future releases for the benefit of
  1405. beginning DEX programmers.
  1406.  
  1407. Needless to say, but: TurboDEX may be copied, crunched and used freely as
  1408. long as the full distribution is with it, and no modifications are made
  1409. to either the executable, the doc or the supportfiles.. Permission granted
  1410. for spreading on (pd) disk series other than that of Fred Fish if costs
  1411. are limited to a copy fee, otherwise you need my written permission.
  1412. I will personally RemHead() and AbortIO() those 'Pd-Distributors' that sell
  1413. this program for more than that.
  1414.  
  1415. For those of you who don't know DonationWare, it's the same as Shareware,
  1416. with three principle differences: You may yourself decide on the size of the
  1417. gift, payment can be done in anything, and you don't have to feel guilty if
  1418. you don't send anything at all. Future versions, and other productions (!)
  1419. depend on YOU. Support quality PD and  Shareware! (i don't necessarily
  1420. mean this program by that).
  1421.  
  1422. Also bug-reports, nice letters, software, 24bit boards are all accepted as
  1423. donation ...
  1424.  
  1425.          Wouter van Oortmerssen ($#%!)
  1426.          Levendaal 87
  1427.          2311 JG  Leiden
  1428.          HOLLAND
  1429.  
  1430. Or even better Email:
  1431.  
  1432.          Wouter@alf.let.uva.nl
  1433.  
  1434.